24U SimpleTalk Plug-In 4.0 Syntax

Registered Custom Script Steps

• STalk Send
• STalk StartServer
• STalk StopServer
• STalk Connect
• STalk Disconnect
• STalk Receive
• STalk Register
• STalk Set

Registered Calculation Functions

• STalk_Version( { versionFormat } )
• STalk_Register( selector )
• STalk_StartServer ( port ; connectionOptions { ; terminator } )
• STalk_StopServer ( serverID )
• STalk_Connect ( host ; port ; connectionOptions { ; terminator } )
• STalk_Disconnect ( serverID )
• STalk_Send ( host ; port ; connectionOptions { ; terminator } ; data )
• STalk_Send ( connectionID { ; encoding } { ; terminator } ; data )
• STalk_Receive ( connectionID { ; encoding } { ; terminator } { ; timeout } )
• STalk_Get( selector { ; connectionOrServerID } )
• STalk_Set( selector { ; connectionOrServerID } ; newValue )

Hosting friendly functionality

In order for a plugin function to work on a server you have to create a config file on that server and set the read permission to everyone. The path of this file should be as follows:

SimpleTalk plugin functions won’t work on server in these cases:

• Plugin doesn’t have a permission to read 24uPluginsAllowedFunctions.txt
• The record in the file 24uPluginsAllowedFunctions.txt with the database name and the list of allowed function doesn’t exist

Format of 24uPluginsAllowedFunctions.txt file

Every line represents one database, first is the name of the database (with suffix .fmp12) followed by a tabulator and then function names separated by ‘|’ (vertical bar). Alternatively, use name of the database (with suffix .fmp12) followed by a tabulator and then the word “any” if you want to allow all the plugin functions. You can find template of 24uPluginsAllowedFunctions.txt in Examples.

Example

In following example:

• Solution MyFileMakerDatabaseOnServer.fmp12 is allowed to use all the functions of any of the 24U plugins
• Solution MyOtherFileMakerDatabaseOnServer.fmp12 is allowed to use functions STalk_Send, STalk_Connect and STalk_Get. Calling function other then those 3 will fail.

MyFileMakerDatabaseOnServer.fmp12   any                                     
MyOtherFileMakerDatabaseOnServer.fmp12  STalk_Send|STalk_Connect|STalk_Get

Complete syntax and description of the plug-in functions

STalk_Version( { versionFormat } )

Returns version string of the active 24U SimpleTalk Plug-In, formatted as requested by the parameter.

Parameters

Parameter values for versionFormat

Description

This function is very important and it has the same output format in all 24U Plug-Ins. You should call this function every time you need to check if the plug-in is properly installed to the FileMaker. Even if the plug-in is not registered (or badly registered), this function should work. Calling this function in the startup script of your solution is recommended.

Result

Returns requested version format or platform. If this function returns “?”, the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.

Example

STalk_Version( "long" )

This will return the plug-in name and its version. In this case, the output is “24U SimpleTalk Plug-In 3.1”.

STalk_Register( selector )

Provides special functionality to operate with plugin serial numbers.

Parameter values for selector

Description

Use this function to register or unregister 24U SimpleTalk Plug-In, to get information about current registration state, or to invoke GUI providing basic registration information and purchase capabilities.

Result

Returns “0” if successful, or “?” in case of an error. Use STalk_Get to obtain the last error code and message.

Example 1

STalk_Register( "STL20C016-BXMW-VNW7-L8AJ-3KGX-VWG8")

This function will register the plug-in with client serial number STL20C016-BXMW-VNW7-L8AJ-3KGX-VWG8 for 16 users.

Example 2

STalk_Register( "user@mail.com" )

In case you do not have a serial number but you want to try the plug-in out, use the string with your email address as selector.

Example 3

STalk_Register( "unregister" )

This function will unregister every serial number related to 24U SimpleTalk Plug-In.

Example 4

STalk_Register( "About window" )

Similar to opening FileMaker preferences, navigating to the Plug-Ins tab and double-clicking on 24U SimpleTalk Plug-In.

Note: All serial numbers here are only for demonstration purposes. They will not work in the plug-in.

STalk_StartServer ( port ; connectionOptions { ; terminator } )

Parameters

connectionOptions

DICOM requirements

• Works only on FMS
• SimpleTalk Helper app has to be installed on machine were FMS is running
• DataAPI user has to be enabled on FMS
• Extended Privileges: Access via FileMaker Data API (fmrest) has to be enabled for dataAPIUser

Built-in handlers:

Description

Start listening for incoming connections on the specified port. When new connection is opened, openhandler is called. The data received through the connection are stored in a queue. When a terminator (CRLF by default) is present in the connection queue, datahandler is called and connectionID is passed to it as parameter. Datahandler is responsible for clearing the beginning of the queue up to the terminator (inclusively) using the STalk_Receive function. With the exception of UDP (see below), failure to call STalk_Receive inside the datahandler can result in an endless loop and make FileMaker unresponsive. When the connection closes, closehandler is called. Neither openhandler nor closehandler are required to call STalk_Receive.

In case of UDP, it does not make any sense to pass connectionID to datahandler because it’s a connectionless protocol. The message is passed directly as a script parameter. There is no need to call STalk_Receive.

In case of selected protocol DICOM, Modality Worklist Service Class Provider (SCP) is created and it starts listening on specified port for incoming Associations. After successfully establishing Association, it expects C-FIND request. Then the requested dataset is parsed into json format and sent to FM through datahandler. SCP is then waiting for STalk_Send to receive the data which is parsed into DICOM format and sent through C-FIND response and Association is released.

Result

Returns server ID if successful, or “?” in case of an error. Use STalk_Get to obtain the last error code and message.

Example (TCP)

STalk_StartServer( 3333 ; "" )

This function will start a TCP server without SSL on port 3333 with default handlers, encoding and terminator. To verify that the server is listening, you can connect to it via:

% telnet localhost 3333

STalk_StartServer( 
  3333; 
  List( 
    "protocol=TCP"; 
    "openHandler=openHandlerScript" ;
    "dataHandler=dataHandlerScript" ;
    "closeHandler=closeHandlerScript"
  )
)

This function will start a server on port 3333 with these scripts as handlers: openHandlerScript, dataHandlerScript and closeHandlerScript. For example,

# openHandlerScript
Set Variable [ $$log ; Value: "Hello!" ]
Set Field [ table::STalkLog ; $$log ]

# dataHandlerScript
Set Variable [ $data ; Value: STalk_Receive( Get(ScriptParameter )) ]
Set Variable [ $$log ; Value: $$log  & ¶ & $data ]
Set Field [ table::STalkLog ; $$log ]

# closeHandlerScript
Set Variable [ $$log ; Value: $$log & ¶ & "Bye!" ]
Set Field [ table::STalkLog ; $$log ]

TCP is connection-oriented communication. The connectionID is passed as a script parameter in dataHandlerScript. Call STalk_Receive to fetch the data and drain the socket buffer.

Example (TCP with SSL)

STalk_StartServer(
    3333 ; 
    List ( 
        "protocol=TCP" ;
        "SSLVersion=TLS" ;
        "openHandler=openHandlerScript" ;
        "dataHandler=dataHandlerScript" ;
        "closeHandler=closeHandlerScript" ;
        "SSLCertificate" & Substitute( table::certificate ; "¶" ; Char(10) ) ;
        "SSLKey=" & Substitute ( table::key ; "¶" ; Char(10) ) ;
        "SSLAuthority=" & Substitute ( table::authority ; "¶" ; Char(10) )  
    )
)

This function will start a TCP server on port 3333 with SSL enabled. Here, table::certificate, table::key and table::authority are multiline text fields in the form:

-----BEGIN CERTIFICATE-----
MIIEMzCCA...
-----END CERTIFICATE-----

or similar. Note that inserting the certificate as a FileMaker text variable causes line breaks be interpreted as carriage return symbols (¶ = Char(13)). To parse the parameters correctly, we need to substitute carriage return symbols with line feeds (\n = Char(10)). To verify that the server is listening, you can connect to it via:

% openssl s_client -connect localhost:3333 -crlf 

Example (UDP)

STalk_StartServer ( 
  3333; 
  List (
    "protocol=UDP";
    "UDPSocketType=Multicast";
    "MulticastGroup=239.255.255.250";
    "dataHandler=dataHandlerScriptUDP"
  )
)

where

# dataHandlerScriptUDP
Set Variable [ $data ; Value: Get(ScriptParameter ) ]
Set Variable [ $$log ; Value: $$log  &  $data ]
Set Field [ table::STalkLog ; $$log ]

This function will start a UDP server on port 3333 that will listen for Multicast messages with SSDP Group. UDP is a connectionless protocol, hence the data handler receives the packet directly as a script parameter. You can verify that server is up using

% nc -u 239.255.255.250 3333

Example (DICOM)

STalk_StartServer (
    3328 ; 
    List (
        "protocol=dicom" ;
        "datahandler=script" ;
        "encoding=UTF-8" ;
        "timeout=10" ; 
        "dataAPIUser=Admin" ;
        "dataAPIPassword=your_very_strong_password" &
        "dataAPILayout=dapi" ;
    ) ;
    "|"
) 

This function will start a DICOM server on port 3328. This can only be run on a FileMaker Server. Setting up DICOM communication is technically involved. Please contact 24U support for help.

STalk_StopServer ( serverID )

Parameters

Description

Close all open connections and shut the specified server down.

Result

Returns “0”, or “?” in case of an error. Use STalk_Get to obtain the last error code and message.

Example

STalk_StopServer( 42 )

Stops server with ID 42 - if existed.

STalk_Connect ( host ; port ; connectionOptions { ; terminator } )

Parameters

connectionOptions

Description

Open a connection to the specified host. Datahandler and close handler are called in the same way as described in STalk_StartServer function reference.

Note: This command is not intended to connect to a server running on the same computer. Doing so will run into errors. (If you want to test the plug-in this way, you need to download two different versions of FileMaker: one for the server and one for the client.)

Result

Returns positive connectionID if successful, or “?” in case of an error. Use STalk_Get to obtain the last error code and message.

Example 1

STalk_Connect ( "1.1.1.1" ; "80" ; "")

Connects to server with IP 1.1.1.1 using port 80.

Example 2

STalk_Connect ( "192.168.0.1"; "33" ; "encoding=UTF-8" ; "\>")

Connects to server with IP 192.168.0.1 using port 33. Encoding for communication UTF-8, character > is used as a terminator.

STalk_Disconnect ( serverID )

Parameters

Description

Close and invalidate the specified connection.

Result

Returns “0” if successful, or “?” in case of an error. Use STalk_Get to obtain the last error code and message.

Example

STalk_Disconnect ( 4 )

Disconnects from with given serverID.

STalk_Send ( host ; port ; connectionOptions { ; terminator } ; data )

Parameters

connectionOptions

Description

Connect to the specified host/port, send the data (and terminator), wait for reply (until the other side closes connection or the time is out), close the connection and return the reply. If autoconvert is specified, each occurrence of local_terminator in data is replaced with terminator. Also, each occurrence of terminator in the reply is replaced with local terminator. This is useful e.g. when you want to send more lines separated with CRLF instead of line ends. (This is the default behaviour.)

Result

Returns the received reply if successful, or “?” in case of an error. Use STalk_Get to obtain the last error code and message.

Example 1

STalk_Send ( "192.168.0.1" ; "1234" ; "waitForReply=no" ; "Hello, world!" )

Sends a string to address 192.168.0.1 using TCP on port 1234 without expecting any reply. The default terminator (CRLF) is used. It returns error when the server is unavailable.

Example 2

STalk_Send ( "192.168.0.1" ; "1234" ; "timeout=10" ; "Hello, server. If you are reading this, the demo worked!" )

Sends a string to address 192.168.0.1 using TCP on port 1234. It waits for a reply by the server (up to ten seconds) and returns the reply as output. For example, if the server side uses the following data handler:

# dataHandlerScript
Set Variable [ $conID ; Get( ScriptParameter ) ]
Set Variable [ $msg ; STalk_Receive( $conID ) ] 
Set Field [ table::STalkMsg ; $msg ]
Send( $conID; "Hello, client. Yes, the demo worked. Miracles do happen." )

then STalk_Send function should return: “Hello, client. Yes, the demo worked. Miracles do happen.” Without such handler, STalk_Send stalls for 10 seconds and returns a timeout error.

Example 3

STalk_Send ( "192.168.0.1" ; "1234" ; "protocol=UDP" ; "Hello, world!" )

Sends a UDP message to “192.168.0.1:1234”. It does not expect any reply. UDP is the most lightweight protocol. It is very fast but will not return an error even when the server is unavailable.

Example 4

STalk_Send ( 
    "" ; 
    "1234" ; 
    List( "protocol=UDP" ; "UDPSocketType=Multicast" ; "MulticastGroup=239.255.255.250" ; "autoconvert=yes" ; "localTerminator=|" ) ; 
    "First message | second message" 
)

Sends a UDP message to multicast group “239.255.255.250”, replacing “|” with the default terminator (CRLF).

STalk_Send ( connectionID { ; encoding } { ; terminator } ; data )

Parameters

Description

Send the data to the other side of an open connection. Automatically append the connection’s terminator to the end of the data.

In case of DICOM protocol, data are datasets delimited with terminator. Each dataset is send separately in C-FIND-RSP according to DICOM standard.

Result

Returns positive number of bytes sent (including terminator) if successful, or “?” in case of an error. Use STalk_Get to obtain the last error code and message.

Example 1

STalk_Send ( 1 ; "SimpleTalk says hi!")

Sends a message to connection 1. Default terminator is used.

Example 2

STalk_Send ( 2 ; "Hex" ; "596f75206465636f646564206d7920736563726574206d657373616765203a2d29" )

Sends some binary data to connection 2 with the hexadecimal equivalent of default terminator: “0d0a”.

Example 3

STalk_Send ( 3 ; "UTF-16" ; "|" ; "Hello|World!")

Sends a message to connection 3. Terminator “|” will be appended to the message. Then, it will be converted to binary using the big endian UTF-16 encoding. Assuming the target server uses the same encoding and terminator, it will receive two messages: “Hello” and “World!”.

STalk_Receive ( connectionID { ; encoding } { ; terminator } { ; timeout } )

Parameters

Description

Read data from an open connection’s buffer up to the terminator. Terminator is read but not returned.

Result

Returns data read (without terminator) if successful, or “?” in case of an error. Use STalk_Get to obtain the last error code and message. (If last error is “0”, it means “?” is the data sent.)

Example

STalk_Receive ( 42 )

Tries to receive data from connection with ID 42.

STalk_Get( selector { ; connectionOrServerID } )

Parameters

Possible values for selector

Description

Returns current value of a global variable or a connection/server option specified by selector.

Result

Returns requested value, or “?” in case of an error. Use STalk_Get to obtain the last error code and message.

Example

STalk_Get( "local-ip" )

Returns IP address of the local pc.

STalk_Set( selector { ; connectionOrServerID } ; newValue )

Parameters

Possible values for selector

Description

Modifies value of a global variable or a connection/server option specified by selector.

Result

Returns 0, or “?” in case of an error. Use STalk_Get to obtain the last error code and message.

Example 1

STalk_Set( "encoding" ; "UTF-16" )

Sets default encoding to “UTF-16”.

Example 2

STalk_Set( "frontmost" ; True )

Brings FileMaker to the front.

Note on data encoding

Encoding of data defines the way how the content passed to SimpleTalk is converted into binary form for sending through network and vice versa. Hence it is important that each side of the connection is synchronized with each other and uses the same encoding.

Note on handlers (openHandler, dataHandler and closeHandler)

FileMaker 19.2.1 and newer added security feature that blocks script calls from Plug-Ins to solutions. In order for handlers to be called, your solution has to enable fmplugin (Validate cross-file plug-in access) privilege set To do so: With your solution opened -> In “File” menu go to “Manage” -> “Security…” then go to “Extended Privileges” tab and enable fmplugin (Validate cross-file plug-in access) privilege set.

Note on terminators

DICOM protocol Limitation: do not use ¶ as a terminator

Terminator is a couple of bytes which splits the transferred data into logical blocks. Of course, both sides of the connection should use the same terminators to achieve the requested behaviour. When a terminator is specified as an optional parameter to some Plug-In’s function, it is encoded into binary form with the same encoding which is given to encode/decode the data. The only exception is default terminator CRLF, which already has exact binary interpretation. When the given terminator is an empty string, its behaviour is a little bit special and depends on the calling function:

For Hex encoding, the terminator must also be a hex string. In this case, the default terminator is “0d0a” (hexadecimal representation of CRLF).

24U SimpleTalk Plug-In status codes